Summary

There is no single way to read a keyboard in NuttX today, and it shows in
the applications.

examples/hidkbd reads a USB HID keyboard as a byte stream.
examples/keyboard reads an upper half keyboard as events. Neither works
with the other, so bringing up a new keyboard means picking the right
example first, and there is no answer for somebody whose keyboard is
neither. examples/lvglterm went further and had three mutually exclusive
input sources, with its own help text explaining that the physical keyboard
options "differ in the data the keyboard device delivers on read(), so pick
the one that matches the hardware". That is the abstraction leaking: a user
had to know the keyboard was USB rather than a matrix in order to compile a
terminal.

This adds system/kbd, which reads any keyboard registered with
keyboard_register(), and converts the terminal and the game to the same
model.

• system/kbd prints every event a keyboard reports, whatever the
  hardware behind it is. With -i it goes the other way and injects into a
  uinput keyboard, either what it reads from its own stdin or every key of
  another keyboard. So an application can be driven from a serial console
  with no keyboard hardware at all, and a real keyboard and an injected one
  can drive it at the same time, which neither can do on its own since an
  application opens a single device.

• examples/lvglterm has two input sources now, touch and physical, and
  the physical one does not ask what kind of keyboard it is.

• games/NXDoom handled KEYBOARD_PRESS and KEYBOARD_RELEASE and
  dropped everything else, so every key reported as KEYBOARD_SPECPRESS
  went nowhere. On the simulator that is already every arrow key, since
  sim_keyboard reports them that way.

  Enter needed handling on both sides, which is worth spelling out because
  it is the whole point of this work: a USB HID keyboard reports it as the
  line feed the key produces, and the simulator reports it as
  KEYCODE_ENTER. Two drivers, two conventions for one key. Both have to
  land on KEY_ENTER, and validating on a single backend is how you end up
  handling only one of them.

This is the application half of the keyboard work. The keycodes and event
types it uses came from apache/nuttx#19586, already merged.

Companion PR, and why CI is red

This has a companion in the kernel repo, apache/nuttx#19592, which updates
the two board configurations that name the option this renames. The two
cannot be green at the same time: CI builds each repo against the other's
master, so this one sees configurations that still name
EXAMPLES_LVGLTERM_INPUT_KBD_USB and _KBD_MATRIX, and the companion sees
an apps master that does not have EXAMPLES_LVGLTERM_INPUT_KBD yet. Both
turn green once both are in.

The failures are limited to the normalisation step of those two
configurations, one line each:

  [1/1] Normalize linum-stm32h753bi/lvglterm_kbda
	modified:   boards/arm/stm32h7/linum-stm32h753bi/configs/lvglterm_kbda/defconfig
        -CONFIG_EXAMPLES_LVGLTERM_INPUT_KBD_USB=y
  [1/1] Normalize esp32s3-m5-cardputer/lvglterm
	modified:   boards/xtensa/esp32s3/esp32s3-m5-cardputer/configs/lvglterm/defconfig
        -CONFIG_EXAMPLES_LVGLTERM_INPUT_KBD_MATRIX=y

Worth flagging for review: no in-tree configuration enables SYSTEM_KBD
yet, so CI never compiles the new application here. The companion PR turns
it on in linum-stm32h753bi:lvglterm_kbda. Until then it was built locally
with the two branches paired, see Testing.

Impact

examples/hidkbd and examples/keyboard stay for now. They are what the
in-tree configurations still name, and removing them has to wait until those
configurations have been moved to system/kbd.

EXAMPLES_LVGLTERM_INPUT_KBD_MATRIX and EXAMPLES_LVGLTERM_INPUT_KBD_USB
are replaced by a single EXAMPLES_LVGLTERM_INPUT_KBD. The two in-tree
configurations that selected either one, on the Linum and on the M5Stack
Cardputer, are updated in the kernel PR. The device path has to be spelled
out for a USB keyboard, since that driver names its devices /dev/kbda
onwards while the option defaults to /dev/kbd0.

EXAMPLES_HIDKBD_ENCODED, NSH_USBKBD and MICROWINDOWS_KBD_RAW all read
a stream of characters rather than events, which now comes from
INPUT_KEYBOARD_BYTESTREAM rather than from the USB HID driver itself. All
three depend on it now, so Kconfig refuses a combination that cannot work
instead of letting the application read events and treat them as text. No
in-tree configuration selects the last two.

The terminal no longer honours cursor keys reported out of band as
ordinary presses of 0x80 to 0x83. The M5Stack Cardputer was the only
driver that did that, and it is converted in the kernel PR, which merges
first.

Nothing else changes for an application that was already reading events.

Testing

Validated on hardware in two independent backends: a USB HID keyboard on a
Linum STM32H753BI, and X11 on the simulator.

system/kbd, reading a real keyboard, event model:

kbd: reading /dev/kbda, keyboard events
press     code  97 'a'
release   code  97 'a'
specpress keycode 7
specrel   keycode 7

Counted rather than eyeballed. Typing normally produced 40 presses and 40
releases, perfectly paired, with no key pressed twice while held, no orphan
release, nothing stuck down at the end, and four keys held at once reported
in the right order. The special keys gave 29 press and release pairs on the
same terms, including two arrows held together.

system/kbd -i, driving a keyboard that does not exist, with a second
instance dumping the same device:

nsh> kbd /dev/ukeyboard &
nsh> kbd -i /dev/ukeyboard
kbd: injecting into /dev/ukeyboard, type to send, Ctrl-D to stop
abc
press     code  97 'a'
release   code  97 'a'
press     code  98 'b'
release   code  98 'b'
press     code  99 'c'
release   code  99 'c'

system/kbd -i with a source, forwarding the USB keyboard into the virtual
one, gave 24 press and release pairs across the crossing with no duplicate,
no orphan and three keys held at once.

examples/lvglterm was driven on the board's LCD from a real USB keyboard,
from the serial console through the uinput bridge, and from both at once
with the USB keyboard forwarded into the same virtual keyboard. The terminal
is the same binary in all three cases and reads a single device.

games/NXDoom was played on the simulator: the menu responds to Enter, the
arrows move, Ctrl fires, Shift runs, Tab opens the map and Escape returns to
the menu. Instrumenting the event handler confirmed the translation, with
Enter arriving as KEYCODE_ENTER and leaving as 13, and the arrows as 5 to
8 leaving as 173 to 176.

Built every configuration in the tree that touches a keyboard, inside the CI
container, with this branch paired against the companion kernel branch so
that the renamed option and SYSTEM_KBD are actually exercised:

### Normalisation
  clean linum-stm32h753bi:lvglterm_kbda     clean olimex-lpc1766stk:hidkbd
  clean esp32s3-m5-cardputer:lvglterm       clean nucleo-h753zi:jumbo
  clean sama5d4-ek:nsh                      clean qemu-intel64:jumbo
### Build
  PASS linum-stm32h753bi:lvglterm_kbda      PASS olimex-lpc1766stk:hidkbd
  PASS esp32s3-m5-cardputer:lvglterm        PASS sim:nxdoom

The CI test lists that cover these boards were also run in full against the
kernel master: arm-08, arm-07 and arm-03, 240 configurations, no
failure.

Two failures seen in the container are environmental and reproduce on an
untouched master: the Xtensa lists fail when the esp-hal-3rdparty
download is truncated, which breaks the .context target for every ESP32-S3
configuration, and ci20 fails to link because the PINGUINOL p32-ld in
the image does not know the target the board asks for:

p32-ld: target elf32-tradlittlemips not found
p32-ld: supported targets: elf32-bigmips elf32-littlemips ...

nxstyle is clean on every file touched.